/**
 ******************************************************************************
 * @file    app_core.h
 * @author  Lucien
 * @version V1.0.0
 * @date    2025-08-22
 * @brief   Core module for message queue and software timer management
 *          Provides:
 *              - Application message queue (app_msg)
 *              - Software timer (app_timer)
 * Usage Example:
 * --------------
 * 1. Initialize the system at startup:
 *      app_core_init();
 *
 * 2. Call the process function in the main loop:
 *      while (1) {
 *          app_core_process();
 *      }
 *
 ******************************************************************************
 * @attention
 * This software is provided "AS IS", without any warranty.
 ******************************************************************************
 */

#ifndef __APP_CORE_H__
#define __APP_CORE_H__

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>
#include "stm32_timer.h"

/* ----------------------------
   Message queue handler type
-----------------------------*/
typedef void (*msg_handler_t)(void *);

/* ----------------------------
   System initialization
-----------------------------*/
void app_core_init(void);

/* ----------------------------
   Message queue APIs
-----------------------------*/
void app_core_process(void);
uint16_t app_msg_post(msg_handler_t handler, void *arg);
uint16_t app_msg_post_front(msg_handler_t handler, void *arg);

/* ----------------------------
   Timer APIs
-----------------------------*/
typedef struct app_timer_t app_timer_t;

struct app_timer_t {
    UTIL_TIMER_Object_t util_timer; /**< Underlying HAL timer object */
    uint32_t period_ms;             /**< Timer period in milliseconds */
    uint8_t repeat;                 /**< Repeat flag: 1=periodic, 0=oneshot */
    msg_handler_t user_cb;          /**< User callback function */
    void *user_arg;                 /**< User callback argument */
};

/* Initialize timer */
void app_timer_init(app_timer_t *timer, msg_handler_t cb, void *arg, uint32_t period_ms, uint8_t repeat);

/* Start timer */
void app_timer_start(app_timer_t *timer);

/* Stop timer */
void app_timer_stop(app_timer_t *timer);

/* Process timer in main loop */
void app_timer_process(void *arg);

/* Convenience: init and start timer */
static inline void app_timer_init_and_start(app_timer_t *timer, msg_handler_t cb, void *arg, uint32_t period_ms, uint8_t repeat)
{
    app_timer_init(timer, cb, arg, period_ms, repeat);
    app_timer_start(timer);
}



#ifdef __cplusplus
}
#endif

#endif /* __APP_CORE_H__ */



